
                      Doors OS version 0.95 Beta
                          by the Doors Team
                       for TI 89 and TI92 Plus

                        Copyright  (C) 1998 
                           Xavier VASSOR
                         Cedric COUFFIGNAL

e-mail: 	xvassor@mail.dotcom.fr
web site: 	http://start.at/doors

                        All rights reserved.

----------------------------------------------------------------------
TABLE OF CONTENTS
----------------------------------------------------------------------

I)   Introduction
II)  Installing Doors OS
III) Installing the explorer 'Doors'
IV)  Programming for Doors OS
V)   Planned Features
VI)  How to contact us
VII) History

----------------------------------------------------------------------
I) Introduction
----------------------------------------------------------------------

        Doors OS is a kernel which will allow the execution of assembly programs on your TI 89 or TI 92 Plus. In fact it extends the built in assembly support.


It features:
        - Library support
        - BSS support
        - Anti Crash protection!  What's more, you can press ESC+ON at any time to exit programs.
        - Runs on both TI 89 and 92 Plus

	Programmers can use the following ditributed libraries!
        - userlib	-> common & password functions
        - graphlib	-> graphical functions
        - filelib	-> file operation functions
	- ziplib 	-> Compression / Extraction  (Made By Marc Teyssier)
	- hufflib	-> Extraction (added for anterior compatibility, use preferably ziplib)
	- hexlib	-> Display Hexa numbers

----------------------------------------------------------------------
II) Installing and using Doors
----------------------------------------------------------------------

Requirements
------------

To install Doors OS you need:
        - A Graph-Link (TM) cable and the TI89 GraphLink software (you can download it at http://www.ti.com/calc) or the TI92 Plus GraphLink software (same address).
        - A TI 89 or a TI 92 Plus:)

Installation
------------

        First, unzip all files contained in DoorsOS.zip into the folder of your choice.

        Then use the Graph-Link to transfer the program named doorsos.89z or doorsos.9xz to your calculator.

        Run doorsos from your calculator (type "doorsos" at the home screen and press Enter). This will install the Doors kernel on the calculator.  You can delete the doorsos file from your calculator after that.

        Now you can run any assembly program: just type it in the home screen like you would a basic program.  If the program needs libraries, they MUST be stored in RAM, not in the Archive. Libraries can be in any folder.

	If you press Shift ON at any time, it will run the program named 'doors', which can be in any folder.

	You can exit all assembly programs at any time, pressing ON+ESC


NOTE: Use this program at you own risk. We can't be held responsible
for any damage done to your calculator.

If your TI89 crashes, press 2nd - Right - Left - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery

If your TI92+ crashes, press 2nd - Lock - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery

----------------------------------------------------------------------
III) Installing the Explorer 'Doors'
----------------------------------------------------------------------

After having installed Doors OS:
Be sure to transfer the following files to your calculator:

	doors		| The explorer
	filelib		| File management library
	graphlib	| Gfx functions
	userlib		| Password and common functions
		by the Doors Team

	ziplib		| Compression library by Marc Teyssier

Now you can lauch the Doors Explorer at any time pressing 'Shift-On'.
Of course it can also be executed from the Home screen
Please read Doors-Explorer.txt for more info about it

----------------------------------------------------------------------
IV) Programming for Doors
----------------------------------------------------------------------

First of all, there are 2 different types programs: programs and libraries The only differences between them is that programs have:
	- An optional comment
	- A main entry point

        Those are the only differences, so programs AND libraries can export functions, BSS blocks, import functions from others programs and libraries, and have an exit point.

How to compile a program or a library
-------------------------------------

Suppose that you unzipped Doors in the folder C:\Doors.  The first thing to do is to add these lines in your autoexec.bat:

SET DOORSOS=C:\DOORS
SET PATH=%PATH%;%DOORSOS%\BIN

Now you can compile a program or library from the Dos command line:

C:\DOORS>Doors <prog>

With "prog" being the name of the .asm file without its extension.

General
-------
        Every program should include the header file "doorsos.h" at the beginning.  To define which calculator the program is designed to run under, the programmer adds the following lines:
        
	xdef    _ti89           to compile a .89z file
        xdef    _ti92plus       to compile a .9xz file

Both lines can be written so that the file is compiled for both calcs.  To learn programming, you should read all docs in the doc directory.


The exit point
--------------

The Anti Crash protection is activated when an error such as an Address error, Illegal instruction, etc.. occurs. It allows you to keep your memory intact.  However, if a program allocated some memory, that memory would be lost.  Our kernel calls the exit point of each program when a crash occurs, so that the program can free memory before ending.
Note that the exit point is optional.

The exit point is defined with;
        xdef    _exit
        (...)
_exit:

At _exit: you will write your exit code. Here is a small example:
        xdef    _exit
        (...)
_exit:
        tst.w   handle  ;tests if handle was allocated when the crash occured
        beq     \notalloc
        move.w  handle,-(a7)
        jsr     doorsos::HeapFree       ;Frees the memory
        addq.l  #2,a7
\notalloc
        rts             ;IMPORTANT ! This code must end with an rts

        (...)
handle  dc.w    0       ;variable supposed to contain a handle number

NOTE: It is important that this code is totally bugfree!  If buggy, there
would be a recursive and endless call to the Anti Crash protection and
the user would have to reset his/her calculator.

How to Export functions
-----------------------
At the beginning of your program or library, you can export functions with a 'xdef    prog@XXXX' line, XXXX being an hexadecimal number. It indicates the index of the exported function.

But programs and libraries should have their include file whenever they export functions. For example, for a library called "graph", suppose that graph@0000 clears the screen. Then in "graph.h" there should be:

graph::clearscr equ     graph@0000

Then if a program or a library wants to use this function it will just have to include "graph.h" at the beginning, and when it wants to clear
the screen, it writes:

        jsr     graph::clearscr


Program example:
----------------
Let's call it 'test'.

        include "doorsos.h"     ;aliases for ROM functions and RAM adresses
        include "lib.h"         ;allows the use of functions exported from 'lib'
        xdef    _ti89
        xdef    _ti92plus       ;compiles for both calcs
        xdef    _main   ;tells that there is an entry point, so we know this is a program
        xdef    _comment ;do this only of you want a comment 
        xdef    test@0000       ;first exported function
        ...
_main:                  ;label of the beginning code of you program
        ...
test@0000:              ;first exported function
        ...
        rts             ;return from function
        ...
        jsr     lib::function   ;calls a function in 'lib'
        rts     ; return from program
        ...
_comment        dc.b    "Program version 2.0",0

        BSS     ;tells there is a BSS block
;define here all vars you want to be in the BSS block.
;they are not initialised
buffer  ds.b    50
        ...

        end     ;tells the assembler that the file is finished.

Note: You don't always need to define comment, or to use a BSS block.

Library example:
----------------

Let's call this library 'lib'.

        include "doorsos.h"     ;aliases for ROM functions and RAM adresses
        xdef    _ti89
        xdef    _ti92plus       ;compiles for both calcs
        xdef    _library        ;tells that this is a library. 
        xdef    lib@0000
        xdef    lib@0001
        ...
        xdef    lib@XXXX

lib@0000:
        ...
        rts     ;exits

lib@0001:
        ...
        rts     ;exits

        ...

        end     ;the file is finished.


----------------------------------------------------------------------
                        V) Planned Features
----------------------------------------------------------------------

Many things will be added in the near future:
        - TSR program management
	- Other compilation modes
	- A doc about the VAT (Variable Allocation Table)
	- Manage archives.. when TI releases info..
        - Anything that you want :)

What's more, when TI releases more info, many more ROM calls will be accessible by programmers.

----------------------------------------------------------------------
                        VI) How to contact us
----------------------------------------------------------------------

You can e-mail us at: <xvassor@mail.dotcom.fr>

If you have a question about programmation, you would better off to mail 
to the Assembly-89 mailing list <assembly-89@lists.ticalc.org>
or the Assembly-92 mailing list <assembly-92@lists.ticalc.org>

Please report any and all bugs you find using DoorsOS, so that we may correct them quickly !!

----------------------------------------------------------------------
                        VII) History
----------------------------------------------------------------------

12/26/1998:
	- Doors OS 0.95 beta released !
	- Improved the Anti Crash protection ! It now recovers better from a crash.
	- Improved the Shift-ON Combo ! It is cleaner !
	- added Font table adresses in DoorsOS.h
	- added Handles.txt in the doc
	- added function getfreearchive in userlib
	- improved filelib::hdltoindex, it will now recognise when you
look for a folder
	- improved filelib::search, it could only return the first file
it found, now you can get the file found after <d1> searches
	- This version should be the last beta version since it is
supposed to be really stable now.


12/06/1998:
	- Doors OS 0.91 beta released !
	- fixed a bug in the Shift-ON combo

11/28/1998:
        - Doors OS 0.9 beta released !
	- Ported the explorer to TI 89 ! Read Doors-Explorer.txt
        - Libraries can be in any folder now !
        - Added the "Shift-ON" combo which launches the program named "doors" at any time.
          For now, it can't display anything if there is an error
        - now automatically replaces the old kernel
        - added an 'uninstall' program
        - added functions: 
        filelib::search
	filelib::createfile
	filelib::resizefile
	filelib::readfile
	filelib::writefile
	graphlib::erase_rect
	graphlib::frame_rect
	graphlib::line

        - enlarged the smallbox in graphlib on the 89.
        - added Macros in doorsos.h : WriteStr, WriteStrA, SetFont, 
	GetKeyStat.
        - fixed bugs in: doorsos::FolderListHandle,doorsos::MainHandle,
                        doorsos::DefTempHandle, Anti Crash protection,
                        userlib::getfreeRAM

10/25/1998:
        - Doors OS 0.85 beta released !
        - Added password functions, InputStr and smallmenu in userlib
        - Included the filelib library: file operation functions
        - Ported hexlib and hufflib to Doors OS.
        - Ported our TI92 explorer to Doors OS! (for TI92+ only)
        - Added doorsos::ST_flags and KEY_SHIFT aliases in doorsos.h
        - fixed bugs in: 
		graphlib::scrtomem & graphlib::memtoscr 
		userlib::FindSymEntry
		Anti Crash protection
		KEY_RIGHT,KEY_LEFT,KEY_UP,KEY_DOWN aliases
		1st EXTRA RAM TABLE entry (thanks to Rusty Wagner)


10/18/1998:
        - Doors OS 0.8 beta released !
        - A new file format has been chosen and implemented.
        - Anti Crash protection implemented !
        - Released the graphlib library and added some functions in userlib.
        - Some bugs were fixed in the compiler.
        - Many more docs even if they aren't complete yet.
        - More samples progs

9/20/1998:
        - Doors OS 0.7 beta released !

